Amiga Inside!

home *** CD-ROM | disk | FTP | other *** search

/ Amiga Inside! / Amiga FD Inside (1995)(Ultramax).iso / berndspd / devtools / intuigen / doc / igrequest.txt < prev next >

Wrap

Text File | 1995-04-21 | 53.7 KB | 1,597 lines

IGRequest.txt doc (C) Copyright 1993 Justin Miller This file may be freely distributed with IntuiGen 2.0. All Other Rights Reserved. The Author makes no warranties, express or implied, as to the accuracy or suitability of the material contained herein. What is IGRequest IGRequest refers to the set of functions found in the IGRequest.c file which manages an IntuiGen generated requester under Intuition (not GadTools). This file documents these functions, their use, and the structures that drive them. Displaying an IGRequest To display an IGRequest, simply use IntuiGen to generate an IGRequest structure and the associated Gadget, NewWindow, and IGInfo structures, and then call IGRequest as follows: main() { struct IGEndList *el; ... el=IGRequest(&MyRequest); /* if el==0, IGRequest failed due to inadequate resources, or other error otherwise IGEndList points to the EndList item that describes the conditions under which IGRequest ended. See the IGEndList structure. */ FreeRemember(&MyRequest.ReqKey,1); } Note that the FreeRemember is necessary under IGRequest, as it leaves string buffers, etc. allocated so you can access them after the routine has returned. This is in contrast to GTRequest. Ending an IGRequest A IGRequest will automatically be ended when the user clicks on a gadget that was defined as an IGEndGadget from within IntuiGen. If you wish to programatically end an IGRequest from a callback function, simply set the request's terminate field to a non-zero value. if the value is greater than zero, the associated data structure is filled with the values from the linked Gadgets in the requester (usually an OK-type response). If the value is less than zero, the structure is not filled. Prop Gadgets IntuiGen generated Prop Gadgets for IGRequest include the main Prop Gadget and two arrows. IGRequest code automatically handles messages from the arrows, moving the Prop Gadget the appropriate direction, and calling the Prop Gadget's ScrollFunc. Note that the values passed to your ScrollFunc are scaled according to the DisplayedX, DisplayedY, MaxX, and MaxY values you set through ModifyIGProp or initially set in the PropInfo structure. See the {"PropInfo" LINK PropInfoStructure} structure for more information. ModifyIGProp is a function found in the IGRequest library. This function MUST be used when dealing with a prop Gadget in an IGRequest instead of Intuition's ModifyProp function. This function is easier to use, as you give it your numbers, not Intuition's numbers, in setting the Prop Gadget's size and position. Creating a ListBox Under IGRequest, List boxes are called Select Boxes. IntuiGen does not generate code for select boxes, but you can manually enter it. To create a SelectBox under IGRequest: 1) Create an IGRequest structure with IntuiGen. The IGRequest should have a vertical Scroll bar in it. The scroll bars height should be the number of entries you want displayed in your SelectBox * 10 + 6. 2) Enter the follow structure before the Proportional Gadget's IGInfo structure in you code: struct SelectBox MySelectBox { NULL, /* Next SBox */ myLeftEdge, myTopEdge, myWidth, myNumberOfLines, /* Number entries displayed at one time used to calculate height=10*Displayed+6 */ 0, /* NumberEntries - Total number of entries in list, may be changed while selectbox running */ SB_RELVERIFY, /* SelectBox Flags - may be one of: SB_TOGGLEALL All entries are TOGGLESELECT, may have any combination turned on or off SB_TOGGLEONE All entries are TOGGLESELECT, only one may be selected at a time, others are turned off SB_RELVERIFY each entry is a simple RELVERIFY Gadget, no toggling supported */ 2, /* BColor1 Color of Left and Top Borders */ 1, /* BColor2 Color of Right and Bottom Borders */ NULL, /* SBoxBorder */ /* Pointer to Border structure to use. Can be initialized, but if not, border is automatically allocated using BColor1, BColor2 */ NULL, /* Pointer to Prop Gadget associated with this SelectBox. Can be left unitialized */ NULL, /* Always Leave NULL */ NULL, /* Entries - Can be initialized, or can be indirectly updated through AddEntry, AddEntryAlpha, etc */ NULL, /* leave NULL */ NULL, /* leave NULL */ ItemSelectedFunc, /* Function to call when an item is selected void (*ItemSelected) (struct IGRequest *,struct SelectBox *, struct SelectBoxEntry *,struct IntuiMessage *); */ ItemDSelectedFunc, /* Function to call when an item is deselected void (*ItemDSelected) (struct IGRequest *,struct SelectBox *, struct SelectBoxEntry *,struct IntuiMessage *); */ NULL, /* leave NULL */ NULL /* UserData - Can be anything */ }; 3) Change the SBox field of the proportional Gadget's IGInfo structure to point to MySelectBox. 4) Change the SBoxes field of your IGRequest structure to point to the above structure you just created. 5) Run the IGRequest. In the InitFunction, call AddEntry, AddEntryAlpha, etc, to add your entries to the SelectBox. See {"SelectBox" LINK SelectBoxFunctions} SelectBox Functions for information on controlling SelectBoxes after the request has been started. Creating a File Requester To open an IGFR File requester, you must first manually enter two structures in addition to your IGRequest structure. Use the following templates to help you out: 1) Enter a IGFileRequest structure: struct IGFileRequest MyFileRequest = { mLeftEdge,mTopEdge, /* LeftEdge, TopEdge of FileRequester */ /* Width and Height are 310 x 122 automatically */ "sys:", /* Current directory is taken from this */ /* Upon exit, chosen file and path name is /* stored here */ "", /* File extension, only files with this extension * will be placed in Requester * if empty, all files are listed */ 2,1, /* Border Colors for SBox border and FileRequest * Border */ IGFR_OKCANCEL | IGFR_NOINFO | IGFR_CURRENTDIR, /*** Flags: IGFR_OKCANCEL Put Ok and Cancel Gadgets in requester IGFR_CURRENTDIR Initialize requester to current directory IGFR_NOINFO Do not display info files IGFR_MULTISELECT Have ToggleSelect FileRequester Selected Entries can be read by cycling through IGDirEntry list pointed to by First. In MultiSelect requesters, this list is not freed upon termination of the request (so that it can be examined later). To free it, FreeRemember the DirKey. When this option is on, a single click selects a directory, a double click opens it. IGFR_VARSSAVED This causes the Selectbox to be completely cleared and the display rebuilt from DirEntries present upon initialization. This can be used when Manually saving variables, including the DirEntry list, Closing the request, and then reopening it with a a directory already read. IGFR_NOFILESELECT Causes File names to be ghosted, not selectable /* These should all be initialized to zero */ 0, /* Init to Zero */ 0, /* Init to Zero */ 0, /* Init to Zero */ 0, /* Init to Zero */ 0, /* Init to Zero */ 0, /* Init to Zero */ 0, /* Init to Zero */ 0, /* Init to Zero */ 0, /* Init to Zero */ 0, /* Init to Zero */ 0, /* Init to Zero */ 0, /* Init to Zero */ 0, /* Init to Zero */ 0, /* Init to Zero */ 0, /* Init to Zero */ /* These can be used by you or other objects */ 0, /* Object field - Pointer to IGObject of which this is part * DOES NOT POINT BACK TO THIS REQUESTER'S * IGOBJECT STRUCTURE. This permits * a file requester to be part of another * IGObject */ 0 /* UserData */ }; 2) Enter a IGObject structure: struct IGObject MyFileReqObject = { MakeIGFileRequest, /* This is a function prototyped in IGFR.h */ /* All File request objects must have this function in this first field */ NULL, /* Init to Zero, MakeIGFileRequest will fill in */ NULL, /* Init to Zero, MakeIGFileRequest will fill in */ NULL, NULL, /* Init to Zero, MakeIGFileRequest will fill in */ &MyFileRequest, 0, /* Init to Zero */ 0, /* Init to Zero */ 0, NULL, /* struct IGObject *Next; - for linking multiple objects for instance,you can have more than one file requester */ 0, /* Prev field - Don't initialize, IGRequest will fix */ "FileSelector", /* Name for this Object to be addressed by via Rexx Programs */ 0 /* APTR UserData; */ }; 3) Change the IGObjects field of the IGRequest to point to MyFileReqObject. 4) Link your program with IGRequest.c and IGFR.c. Note that the size of an IGFR File requester is pre-determined at 310 x 122. You may have some problems with the arrows on the file requester's scroll bar. If you define a scroll bar elsewhere, the chipdata for the arrows will be duplicated between your file and IGFR.c. In this case you should comment one out. You will also have to insure that this arrow data is moved into chip memory. Most compilers accept the chip keyword to do this, however some don't. For this reason, the chip keyword is not included in the arrow image definitions in IGFR.c. If your compiler supports this keyword you should add it. Otherwise you will have to copy the image data from fast ram to chip ram using AllocMem and CopyMem. To determine whether the image definitions for the arrows are included in IGFR.c or not, there is a define at the beginning of the file, INCLUDEARROWDATA. If this define is commented out, the arrow data will not be included. If this constant is defined, the arrow data will be included. For information on controlling an IGFR file request as it is running, consult FileRequest Functions. Opening Multiple Requests IGRequest is fully re-entrant, and can therefore be called recursively and from multiple tasks. IGRequest does not support the simultaneous operation of several requests from the same task like GTRequest does. You either must block the first any open requests, and call IGRequest to display your new requester, or you must start another thread and call IGRequest to display your new requester. The first method would look something like this: main() { ... IGRequest(&MyRequest1); ... FreeRemember(&MyRequest1.ReqKey,1); ... } void SomeGadgetUpFunc(struct IGRequest *req, struct IntuiMessage *msg) { BlockIGInput(req); IGRequest(&MyRequest2); ... FreeRemember(&MyRequest2.ReqKey,1); ... UnBlockIGInput(req); } Using the second method, main would remain the same, and SomeGadgetUpFunc would read as follows: void SecondRequest(void); void SomeGadgetUpFunc(struct IGRequest *req, struct IntuiMessage *msg) { NewThread(SecondRequest); } void SecondRequest (void) { ... IGRequest(&MyRequest2); ... FreeRemember(&MyRequest2.ReqKey,1); } BitField Macros These are defined in IntuiGen.h: #define FLAGOFF(x,flag) ((x)&=0xffffffff^(flag)) #define FLAGON(x,flag) ((x)|=(flag)) #define ISFLAGON(x,flag) ((x) & (flag)) #define ISFLAGOFF(x,flag) (!(ISFLAGON(x,flag))) IGFR Flags These are defined in IntuiGen.h: #define IGFR_VARSSAVED 256 #define IGFR_OKCANCEL 4 #define IGFR_CURRENTDIR 16 #define IGFR_NOINFO 64 #define IGFR_MULTISELECT 128 #define IGFR_INCLUDEASSIGNS 512 #define IGFR_NOFILESELECT 1024 IGRequest Flags These are defined in IntuiGen.h: #define IG_ADDGADGETS 1 #define IG_INITREQUESTERTOOPEN 2 #define IG_INITDATASTRUCT 4 #define IG_RECORDWINDOWPOS 8 SelectBox Structure This is defined in IntuiGen.h: struct SelectBox { struct SelectBox *Next; USHORT LeftEdge; USHORT TopEdge; USHORT Width; USHORT Displayed; /* Number entries displayed at one time used to calculate height=10*Displayed+6 */ USHORT NumberEntries; /* Total number of entries in list, may be changed while selectbox running */ USHORT Flags; /* SB_TOGGLEALL All entries are TOGGLESELECT, may have any combination turned on or off SB_TOGGLEONE All entries are TOGGLESELECT, only one may be selected at a time, others are turned off SB_RELVERIFY each entry is a simple RELVERIFY Gadget, no toggling supported */ UBYTE BColor1,BColor2; /* BColor1 Color of Left and Top Borders BColor2 Color of Right and Bottom Borders */ struct Border *SBoxBorder; /* Pointer to Border structure to use. Can be initialized, but if not, border is automatically allocated using BColor1, BColor2 */ struct Gadget *Prop; /* Pointer to Prop Gadget associated with this SelectBox. Can be left unitialized */ struct Gadget *GList; /* leave NULL */ struct SelectBoxEntry *Entries; /* Can be initialized, or can be indirectly updated through AddEntry, AddEntryAlpha, etc */ struct SelectBoxEntry *Selected; /* leave NULL */ struct Remember *SBKey; /* key upon which all necessary structures are allocated */ /* is freed upon exit from IGRequest */ void (*ItemSelected) (struct IGRequest *,struct SelectBox *, struct SelectBoxEntry *,struct IntuiMessage *); /* Function to call when an item is selected */ void (*ItemDSelected) (struct IGRequest *,struct SelectBox *, struct SelectBoxEntry *,struct IntuiMessage *); /* Function to call when an item is deselected */ struct IGObject *IGObject; /* Object which this SelectBox is part of */ APTR UserData; }; SelectBoxEntry Structure This is defined in IntuiGen.h: struct SelectBoxEntry { UBYTE *Text; /* Pointer to text string to be used */ UBYTE Color; /* Color of text printed in Select Box */ USHORT Flags; /* SB_SELECTED Item is selected, should be highlighted SB_NOTSELECTED Item is not selected, not highlighted */ USHORT ID; /* ID, SBox Entries must be numbered sequentially, from 0 to X, Use FixIDs () to accomplish this */ struct Gadget *Gadget; /* Gadget this entry is currently linked to will change as user scrolls through select box */ void (*ItemSelected) (struct IGRequest *,struct SelectBox *, struct SelectBoxEntry *,struct IntuiMessage *); /* Function to call when this item is selected, called after Global ItemSelected () from SelectBox structure is called. */ void (*ItemDSelected) (struct IGRequest *,struct SelectBox *, struct SelectBoxEntry *,struct IntuiMessage *); /* Function call when this item is deselected, Everything same as ItemSelected above */ struct SelectBoxEntry *Next,*Prev; /* Used to link together SBox Entries Only the next link needs to be filled in, IGRequest will call FixLinks () to fill in Prev links */ struct IGObject *IGObject; /* Object which this SBEntry is part of */ APTR UserData; }; IGBoolInfo Structure This is defined in IntuiGen.h: struct IGBoolInfo { USHORT Type; /* must be GADG_BOOL. Can also contain: GADG_INITONCE Initialize the on/off state of Gadget first time requester is opened. Leave as user leaves it thereafter. GADG_INITALWAYS Initialize the on/off state of Gadget every time the requester is opened. GADG_ONESELECTED If this is part of a series of mutual exclude toggleselect gadgets, one must always be selected. BOOL_FILL Copy Values to and from Datastruct given in IGRequest using the BitToSet in the longword at offset DataStructOffset as the source/destination See below. */ USHORT InitialValue; /* For ToggleSelect Gadgets. Can be set to NULL Gadget is off GFLG_SELECTED Gadget is on */ USHORT DataStructOffSet; /* OffSet of integral field to set to true or false on exit from IGRequest (toggleselect gadgets only) */ UBYTE BitToSet; /* Bit in data field to set to true or false */ void (*GUpFunction) (struct IGRequest *,struct IntuiMessage *); void (*GDownFunction) (struct IGRequest *,struct IntuiMessage *); void (*DClickFunction) (struct IGRequest *,struct IntuiMessage *); struct IGObject *IGObject; /* Object which this Bool Gadget is part of */ UBYTE *RexxName; /* Name that Arexx commands can refer to this gadget by */ APTR UserData; /* FOR MUTUAL EXCLUDE TOGGLESELECT GADGETS: Under IGRequest the MutualExclude long word in the Gadget structure has been implemented. Each group of mutual exclude Gadgets should be assigned a bit, and this bit set in each Gadget's structure in the MutualExclude field. Gadget's that have the same bit set will not be able to be activated simultaneously (turning one on will turn the other off). NOTE: Using the MutualExclude field to contain other information in ToggleSelect Gadgets will have undesirable results */ }; IGStringInfo Structure This is defined in IntuiGen.h: struct IGStringInfo { USHORT Type; /* must be GADG_STRING */ /* Can also contain STRING_FLOAT This gadget contains a floating point numeral Structure field to be filled is of type IGFloat (typedefed as float) STRING_LONG This gadget contains a long integer, structure field to be filled is of type LONG STRING_SHORT This gadget contains a short integer structure field to be filled is of type SHORT STRING_LOWLIMIT StringLow is to be imposed on this string gadget STRING_HIGHLIMIT StringHigh is to be imposed on this string gadget STRING_FILL fill structure field at offset in DataStructOffSet when ending of type FILLSTRUCT is chosen STRING_INITONCE Setting this flag will cause whatever is in the IGInfo->InitialValue field to be copied into the buffer. This flag is then cleared. STRING_INITALWAYS Setting this flag will cause whatever is in the IGInfo->InitialValue field to be copied into the buffer every time the requester is opened. NOTE: If IGRequest allocates a buffer for a string, it will always copy IGInfo->InitialValue to the buffer, which would otherwise be completely blank. It will only do this when it actually allocates the buffers, which would be the first time through, or the first time through after you Free them. */ UBYTE *InitialValue; /* pointer to string to copy into buffer when requester begins */ UBYTE *DisAllowedChars; /* pointer to string, characters in which are not to be allowed in this string gadget */ USHORT DataStructOffSet; /* offset from structure of field that contents of this string gadget should be copied to */ /* These set limits on contents of numerical string gadgets */ LONG StringHigh; LONG StringLow; struct Gadget * NextStringGadget; /* pointer to string Gadget to activate when a GadgetUp msg is recieved from this one */ void (*GUpFunction) (struct IGRequest *,struct IntuiMessage *); void (*GDownFunction) (struct IGRequest *,struct IntuiMessage *); void (*DSelectFunction) (struct IGRequest *,struct IntuiMessage *); /* Same as GUpFunction but will always be called, either on GadgetUp, or when another gadget is activated, thereby deactivating this one */ struct IGObject *IGObject; /* Object which this String Gadget is part of */ UBYTE *RexxName; /* Name that Arexx commands can refer to this gadget by */ APTR UserData; }; IGPropArrowInfo Structure This is defined in IntuiGen.h: struct IGPropArrowInfo { USHORT Type; /* must be GADG_ARROW */ struct Gadget *Prop; /* Pointer to prop Gadget with which this arrow is associated. Need not be initialized, PropInfo will point to arrow Gadget which will Point here, so that the prop field can be initialized automatically by IGRequest */ void (*GUpFunction) (struct IGRequest *,struct IntuiMessage *); /* function to call on GadgetUp */ void (*GDownFunction) (struct IGRequest *,struct IntuiMessage *); /* Function to call on GadgetDown */ struct IGObject *IGObject; /* Object which this PropArrow is part of */ APTR UserData; }; IGPropInfo Structure This is defined in IntuiGen.h: struct IGPropInfo { USHORT Type; /* must be GADG_PROP */ void (*ScrollFunc) (struct IGRequest *,struct Gadget *,LONG,LONG); /* called when arrows clicked, held down, or prop played with */ /*Args: ScrollFunc(IGRequest,gadget,XPos,YPos)*/ struct SelectBox *SBox; /* Pointer to SelectBox with which this Prop Gadget associated */ struct Gadget *LUArrow; /* Pointer to the Left or Up arrow Gadget */ struct Gadget *RDArrow; /* Pointer to the Right or Down arrow Gadget */ USHORT MaxX; /* Number of Items to be displayed horizontally */ USHORT MaxY; /* Number of Items to be displayed vertically */ USHORT DisplayedX; /* Number displayed at one time */ USHORT DisplayedY; USHORT Top; /* Topmost item currently being displayed */ USHORT Left; /* Leftmost item currently being displayed */ struct IGObject *IGObject; /* Object which this Scroll Bar is part of */ APTR UserData; }; IGObject Structure This is defined in IntuiGen.h: /* struct IGObject */ /* This is somewhat esoteric, but works as follows: An Object could be anything the user thinks up, such as a FileRequester, which should be part of a requester. The InitFunction is called first. It should allocate and initialize the constituent Gadgets, Borders, Images, IntuiTexts, SelectBoxes, or other IGObjects (which must be placed at the end of the list in order to be recognized), accompanying IGInfo structures, and add them to the appropriate linked lists. It should also tie in any additional functions to be called upon certain events. For General message functions - the ones pointed to in the IGRequest structure itself (for instance RAWKEY, InitFunction, or DISKREMOVED), a passthru feature should be provided as follows: The address in the IGRequest structure should be saved in the structure pointed to by IGObject.Address The address of the new function should be put in When the new function is called, it should service the last object of the appropriate type whose service flag is not set. It should immediately set the serviced flag in that object. It should then perform whatever processing is necessary for that object. Last, it should that objects passthru function. The address should be saved in the structure pointed to by IGObject address and not in a static variable so that the function is fully reenterant and can be multitasked, and nested calls (from nested IGRequests) can be made to it. The serviced flag is to allow multiple objects of complex types to exist in the same requester. Later, in the CleanUp Routine, each object should replace the original value of each of these general functions that it used into the IGRequest struct. Since these objects are handled in reverse order, that will restore the IGRequest structure to its previous state PROVIDING that the only time the values of the General functions are changed are in the InitFunctions and the cleanup. NO OTHER ROUTINES MAY CHANGE THESE FUNCTIONS DURING THE EXECUTION OF IGREQUEST IF IGOBJECTS ARE TO BE USED. REMEMBER: If an Object adds anything to one of the linked lists, and then frees it upon exit from the requester, it also must remove its reference from the linked list. Failure to do so will cause a Guru. */ struct IGObject { BOOL (*InitFunction) (struct IGRequest *,struct IGObject *); /* The InitFunction should return 1 on error */ /* The following two can be the same, but should be provided if the InitFunction Allocates anything, providing a means to free it. Any thing allocated on the IGRequest structure's key will be taken care of, DO NOT FREE IT IN THESE FUNCTIONS! Arguments for both (so they are interchangeable, if desired): Function (IGRequest,IGObject,EndListItem); ALL FUNCTIONS ARE PASSED POINTERS ONLY */ void (*AbortFunction) (struct IGRequest *,struct IGObject *,struct IGEndList *); void (*RequestEndedFunction) (struct IGRequest *,struct IGObject *,struct IGEndList *); /* The Rexx Function is sent rexx messages for this object. It is up to it to process them. The Arexx command line would look like this: RexxName Command Arg1 Arg2...Argn Where RexxName is this objects name as defined below, and the command and arguments are specific to this object. This function should return True if it processed the Rexx Message, and False if the Rexx Message needs further processing. */ BOOL (*RexxFunction) (struct IGRequest *,struct IGObject *,struct RexxMsg *); UBYTE *Class; /* Label for this Object Class */ APTR Address; /* Pointer to data structure for this Object */ BOOL Serviced; USHORT GadgetYOffSet; /* Number of pixels to add to TopEdge of Gadgets to compensate for larger system fonts used in title bars. If this is zero, the default system font is equivalent in vertical size to Topaz 8 (first usable row in Windows has Y coord of 11 */ struct IGObject *IGObject; /* Object which this Object is part of */ struct IGObject *Next; struct IGObject *Prev; /* Need not be initialized, IGRequest will fix */ UBYTE *RexxName; /* Name for this Object to be addressed by via Rexx Programs */ APTR UserData; }; IGFileRequest Structure This is defined in IntuiGen.h: /* This is an IGObject. Code for this object is in the file IGFR.c in the source directory. An example is in the examples directory under FileRequest.c. To use this, first fill out an IGFileRequest stucture. Next Fill out an IGObject structure. The InitFunction should be MakeIGFileRequest. The Address field should point to the IGFileRequest structure. All can be left blank. */ struct IGFileRequest { USHORT LeftEdge,TopEdge; /* LeftEdge, TopEdge of FileRequester */ UBYTE FileName[200]; /* Current directory is taken from this */ /* Upon exit, chosen file and path name is /* stored here */ UBYTE Extension[10]; /* File extension, only files with this extension * will be placed in Requester */ UBYTE BColor1,BColor2; /* Border Colors for SBox border and FileRequest * Border */ USHORT Flags; /* IGFR_OKCANCEL Put Ok and Cancel Gadgets in requester IGFR_CURRENTDIR Initialize requester to current directory IGFR_NOINFO Do not display info files IGFR_MULTISELECT Have ToggleSelect FileRequester Selected Entries can be read by cycling through IGDirEntry list pointed to by First. In MultiSelect requesters, this list is not freed upon termination of the request (so that it can be examined later). To free it, FreeRemember the DirKey. When this option is on, a single click selects a directory, a double click opens it. IGFR_VARSSAVED This causes the Selectbox to be completely cleared and the display rebuilt from DirEntries present upon initialization. This can be used when Manually saving variables, including the DirEntry list, Closing the request, and then reopening it with a a directory already read. IGFR_NOFILESELECT Causes File names to be ghosted, not selectable */ /* These should all be initialized to zero */ BYTE CLBit; /* req->CallLoop bit allocated */ BPTR Lock; /* For reading directory */ struct FileInfoBlock *FInfo; /* For reading directory */ struct SelectBox *SBox; /* SelectBox (allocated) */ struct Gadget *Gadgets; /* Gadgets (allocated */ struct Border *Borders; /* Borders (allocated */ struct Remember *Key; /* Key upon which above is allocated automatically freed on exit */ struct Remember *DirKey; /* Key upon which current directory entries are allocated, automatically freed */ struct IGDirEntry *First; /* Pointer to first DirEntry in linked list */ USHORT Number; /* Number of entries in DirEntry list */ void (*LoopFunction) (); /* Variable in which IGRequest's LoopFunction * is saved */ void (*DRemoved) (); /* Variable DiskRemoved saved to */ void (*DInserted) (); /* Variable DiskInserted saved to */ struct IGDirEntry *DCEntry; /* Last Entry Selected (for double click */ ULONG DCSecs,DCMics; /* Double click time, seconds */ /* These can be used by you or other objects */ struct IGObject *Object; /* Pointer to IGObject of which this is part * DOES NOT POINT BACK TO THIS REQUESTER'S * IGOBJECT STRUCTURE. This permits * a file requester to be part of another * IGObject */ APTR UserData; /* UserData */ }; IGDirEntry Structure This is defined in IntuiGen.h: /* These are the structure and flag definitions for the linked list pointed to by the First field in the IGFileRequest structure. The current directory is stored thus. */ #define IGDE_DIR 1 /* This entry is directory */ #define IGDE_DISPLAYED 2 /* This entry matches current file matching specs */ #define IGDE_SELECTED 4 /* This entry is selected (in MULTISELECT FileRequester's only */ #define IGDE_FILESONLY 8 /* These are for use with the DupDirList function */ #define IGDE_NOTDISPLAYED 16 /* only. They are not written into the */ #define IGDE_NOTSELECTED 32 /* IGDirEntry structure. */ #define IGDE_ALL 0 #define IGDE_DIRSONLY 1 struct IGDirEntry { UBYTE *FileName; UBYTE Flags; struct SelectBoxEntry *SBE; struct IGDirEntry *Next,*Prev; }; IGEndList Structure This is defined in IntuiGen.h: struct IGEndList { ULONG Class; /* IDCMP class of message to end requester */ USHORT Code; /* IDCMP code of message to end requester */ USHORT Qualifier; /* IDCMP qualifier of message to end requester */ struct Gadget *Gadget; /* if Gadget msg, address of gadget to end requester */ BOOL (*OKToEnd) (struct IGRequest *,struct IntuiMessage *); /* 1=end request, 0=don't end request */ void (*Function) (struct IGRequest *,struct IntuiMessage *); /* Function to call if this ending is taken */ BOOL FillStruct; /* Fill DataStructure if this ending is taken? */ }; IGKeyCommand Structure This is defined in IntuiGen.h: struct IGKeyCommand { USHORT Command; /* RAWKEY code*/ USHORT ASCIICommand; /* ASCII code for unqualified key. Fill in either this or Command. If this is filled in, the equivalent Rawkey is looked up from the current keymap and placed in Command by IGRequest. If both ASCIICommand and Command are 0, RawKey code of 0 is assumed. */ USHORT Qualifier; /* Qualifier */ struct Gadget *Gadget; /*pointer to gadget that code/qualifier will activate */ }; IGMenu Structure This is defined in IntuiGen.h: struct IGMenu { USHORT Code; /* Number that will be recieved in Code field of IntuiMessage when this MenuItem Chosen */ void (*Function) (struct IGRequest *,struct IntuiMessage *); /* Function to call when MenuItem Chosen */ UBYTE *RexxName; }; MessageHandler Structure This is defined in IntuiGen.h: /* Use this to set up handling routines for classes of messages or sequences of messages not supported by IGRequest. (Shift Click, Triple Click, etc.) */ struct MessageHandler { UBYTE *Name; /* Name of this class. Can be whatever you want */ BOOL (*IsType) (struct IGRequest *,struct IntuiMessage *); /* Called on every message. Should return 1 if the message constitutes the correct type, 0 otherwise */ void (*HandlerFunction) (struct IGRequest *,struct IntuiMessage *); /* If IsType () returns 1, this is called */ struct MessageHandler *Next; }; IGRequest Structure This is defined in IntuiGen.h: struct IGRequest { struct NewWindow *NewWindow; /* pointer to NewWindow to open */ /* pointer to opend window will be placed in IGRequest->Window field */ struct Window *Window; /* pointer to already opened window IGRequest will not close window unless it opened it */ UBYTE *ScreenName; /* ScreenName to use with this window */ struct Requester *RequesterToOpen; /* pointer to Intuition Requester to open */ struct Requester *Requester; /* Pointer to already open Intuition Requester */ struct IGMenu *Menus; /* pointer to null terminated array of IGMenu structures for handling of menus */ struct IGEndList *EndList; /* pointer to null terminated array of IGEndList structures */ struct IGKeyCommand *KeyCommands; /* pointer to null terminated array of IGKeyCommand structures */ struct Gadget *Gadgets; /* pointer to first gadget in requester to use */ USHORT Flags; /* Possible Values: IG_INITREQUESTERTOOPEN Causes RequesterToOpen to be Initialized before opening IG_ADDGADGETS Causes Gadgets to be Added to Window or requester IG_INITDATASTRUCT Causes Data Struct to be Initialized to default values for string and Toggleselect flag fields, useful with newly allocated Data Structures */ struct Gadget *StringToActivate; /* Pointer to string Gadget to activate when requester first opened */ struct Menu *MenuStrip; /* pointer to menu list to add to window when opened */ struct Border *Borders; /* pointer to Border list to draw into window */ struct Image *Images; /* pointer to Image list to draw into window */ struct IntuiText *ITexts; /* pointer to IntuiText list to write into window */ struct SelectBox *SBoxes; /* pointer to first SelectBox to put into this window */ struct IGObject *IGObjects; /* pointer to first IGObject structure */ APTR DataStruct; /* pointer to structure to fill */ struct Remember *ReqKey; /* Strings without buffers allocated on this */ void (*InitFunction) (struct IGRequest *); /* function to call when requester first opened */ BYTE Terminate; /* Can be set by outside routines to */ /* force request to end, >0==FillStruct, <0==!FillStruct */ struct MsgPort *IComPort; /* Internal use only. Initialize to 0 */ APTR InternalData; /* Internal use only. Initialize to 0 */ void (*DSelectFunction) (struct IGRequest *,struct IntuiMessage *); /* To be called any time String Gadget is * De-Selected */ void (*EndFunction) (struct IGRequest *,struct IntuiMessage *); /* To be called when requester ends. * This is called after any EndList EndFunction */ void (*LoopFunction) (struct IGRequest *); /* This function is called repeatedly * while there is not a message at the * Window port and while CallLoop!=0 */ /* When using IGObjects, LoopFunction should be passed through. If any of the Functions or Objects in the list need to be called, the whole list must be called. Each function then, should perform the obligatory task of finding its corresponding object (the last one of its type in the IGObject list that does not have its serviced flag set) and set the serviced flag so that the function that does need to be called can find its object. After setting the serviced flag, each function can then check some internal variable, or CallLoop to see if it needs to do anything further. It then must call whatever function it replaced from the IGRequest structure. To insure that one function does not clear CallLoop when another function needs it set, each function should call AllocCLBit to be assigned a bit in the CallLoop variable. This function should only change this bit. LoopBitsUsed records what bits are free and which ones have been allocated */ ULONG CallLoop; ULONG LoopBitsUsed; struct MsgPort *ArexxPort; void (*ArexxFunction) (struct IGRequest *,struct RexxMsg *); /* Port to which Arexx messages are coming in. IGRequest will process and reply to the following commands: KEYCLICK qualifiers key GADGETCLICK gadgetname SETSTRINGGAD stringgad string If IGRequest can't find the specified gadget, or encounters an unrecognized commands, the RexxMsg will be passed to your ArexxFunction to process. If an ArexxFunction is not specified, an error will be set. IGRequest replies to all RexxMsgs. */ ULONG AdditionalSignals; /* Additional signals to Wait on */ BOOL (*SignalFunction) (struct IGRequest *,ULONG); /* Called before IGRequest goes into wait state. Use this to test Ports that you are waiting on through AdditionalSignals for messages. Process one message at a time. Return 0 if IGRequest can go into a wait state, 1 if you require further processing time, in which case your function will be called again (after checking the window port, calling the loopfunction, etc.) SignalFunction (IGRequest,Signals); */ /* The Following correspond with IDCMP messages, and are called when that * message is recieved */ void (*GUpFunction) (struct IGRequest *,struct IntuiMessage *); void (*GDownFunction) (struct IGRequest *,struct IntuiMessage *); void (*MouseButtons) (struct IGRequest *,struct IntuiMessage *); void (*MouseMove) (struct IGRequest *,struct IntuiMessage *); void (*DeltaMove) (struct IGRequest *,struct IntuiMessage *); void (*RawKey) (struct IGRequest *,struct IntuiMessage *); void (*IntuiTicks) (struct IGRequest *,struct IntuiMessage *); void (*DiskInserted) (struct IGRequest *,struct IntuiMessage *); void (*DiskRemoved) (struct IGRequest *,struct IntuiMessage *); void (*MenuVerify) (struct IGRequest *,struct IntuiMessage *); void (*MenuPick) (struct IGRequest *,struct IntuiMessage *); void (*SizeVerify) (struct IGRequest *,struct IntuiMessage *); void (*NewSize) (struct IGRequest *,struct IntuiMessage *); void (*ReqVerify) (struct IGRequest *,struct IntuiMessage *); void (*ReqSet) (struct IGRequest *,struct IntuiMessage *); void (*ReqClear) (struct IGRequest *,struct IntuiMessage *); void (*ActiveWindow) (struct IGRequest *,struct IntuiMessage *); void (*InActiveWindow) (struct IGRequest *,struct IntuiMessage *); void (*RefreshWindow) (struct IGRequest *,struct IntuiMessage *); void (*NewPrefs) (struct IGRequest *,struct IntuiMessage *); void (*CloseWindow) (struct IGRequest *,struct IntuiMessage *); void (*DoubleClick) (struct IGRequest *,struct IntuiMessage *); struct MessageHandler *OtherMessages; APTR UserData; }; cismember Function /* returns TRUE is character c is in string s, other wise returns false */ int cismember (char c,char *set); delchars Function /* deletes n chars starting at position p from string s */ void delchars (char *s,USHORT p,USHORT n); strelim Function /* if k==FALSE deletes every occurance of any character in string elim in * string s * if k==TRUE deletes every occurance of any character not in string elim in * string s * returns true if any characters were deleted */ BOOL strelim (char *s,char *elim,BOOL k); PullWord Function/Macros /* Convenient routine to pull words off of a string. Multiple words in * quotes as single words. Keeps track of nested Quotes ('"Nested quotes"'). * slist is the string to pull words off of. word is the buffer to copy * the word to. index is the index to start at in slist. delim is a string * that contains characters that should be ignored, but counted as delimiters. * retdelim contains characters that should be used as delimiters and returned * as words by themselves. len is the length of word. */ #define RxPullWord(rxcom,combuf,ndx,len) \ PullWordIndex(rxcom,combuf,ndx," ,","",len) LONG PullWordIndex (UBYTE *slist,UBYTE *word,USHORT index, UBYTE *delim,UBYTE *retdelim,USHORT len); RawKeyToAscii Function /* Takes RAWKEY code and qualifier (from an IntuiMessage) and returns * ASCII equivalent */ UBYTE RawKeyToAscii (USHORT code,USHORT qual); ClearWindow Function /* * ClearWindow Function, clears inside of window to background (0) */ void ClearWindow (struct Window *w); ModifyIGProp Function /* Refreshes values in IGInfo, PropInfo structures for IG Prop Gadget */ /* You MUST use this instead of Intuition's ModifyProp */ void ModifyIGProp (struct IGRequest *req, /* IGRequest containing prop gadget */ struct Gadget *prop, /* Prop Gadget */ USHORT mx,my,dx,dy, /* MaxX, MaxY, DisplayedX, DisplayedY, */ USHORT top,left); /* Top position, Left Position */ SendIntuiMsg Function /* Sends an IntuiMessage to an IGRequest over an internal port (not the * window port). IGRequest treats messages coming to this port as if they * had came directly to the window port. * NOTE: These messages should be freed using the macro FreeIntuiMsg(). * They are not intended to be replied to. */ BOOL SendIntuiMsg (struct IGRequest *req,ULONG Class,ULONG Code, USHORT Qualifier,APTR IAddress); /* Frees an IntuiMessage allocated by SendIntuiMsg. Use this instead of * ReplyMsg. */ #define FreeIntuiMsg(x) FreeMem(x,sizeof(struct IntuiMessage)) StimulateGadget Function /* Causes a Gadget to look like it was clicked by the user * Activates string gadgets * Selects or deselects toggle gadgets * Causes select and then deselect for Bool Gadgets * DOES NOT SEND ANY MESSAGES OR EFFECT BEHAVIOR OF PROGRAM - SIMPLY * CHANGES GADGET APPEARANCE */ void StimulateGadget (struct IGRequest *req,struct Gadget *gadg); GadgetClick Function /* Causes the program to behave as if they user clicked on a * Gadget. Sends appropriate messages to IGRequest, causes gadget * to be stimulated. */ BOOL GadgetClick(struct IGRequest *req,struct Gadget *gadg); KeyClick Function /* Sends a RAWKEY message to an IGRequest. keyinfo points to a string * that can contain any of the following letters in any order: * s - shift * c - control * a - alt * A - command (Amiga) * Letters besides these will be ignored. Case is significant. * key contains the ASCII code of the key to send. It is converted * to Rawkey using the current default keymap. */ BOOL KeyClick (struct IGRequest *req,UBYTE *keyinfo,UBYTE key); MenuPick Function /* This function will cause the program to behave as if the user had selected the given menu item manually. */ BOOL MenuPick (struct IGRequest *req,struct IGMenu *igm); SetStringGad Function /* Copies string to a string Gadget buffer, refreshes string gadget, * and sends GADGETUP and GADGETDOWN messages to IGRequest. */ void SetStringGad (struct IGRequest *req,struct Gadget *gadg,UBYTE *string); BlockIGInput Function /* BlockIGInput Function opens an blank intuition requester on top of an IGRequest, thereby blocking its input */ void BlockIGInput(struct IGRequest *req); UnBlockIGInput Function /* UnBlockIGInput closes blank requester opened by BlockIGInput, thereby permitting messages to come through again */ void UnBlockIGInput(struct IGRequest *req); BoolRequest Function /* Opens an Intuition requester over IGRequest req, with message string, and 2 Gadgets, labeled by strings g1 and g2. returns 0 if g1 is selected, 1 if g2 is selected */ BOOL BoolRequest (struct IGRequest *req,UBYTE *string,UBYTE *g1,UBYTE *g2); IGRequest Function /* Handles all necessary procedures to display and handle IGRequest req returns pointer to endlist item that caused request to terminate, if termination was caused by Terminate field in req being set to TRUE, returns pointer to allocated (on req->ReqKey) endlist struct with class of IG_REQTERMINATE, returns NULL on error */ #ifdef IGFAR /* define this in your source for far IGRequest */ /* Be careful if you use precompiled headers!!! */ __far #endif /* IGFAR */ struct IGEndList *IGRequest (struct IGRequest *req); IGRemove Functions /* For removing a Gadget from the IGRequest's Gadget list that was * added by an IGObject. This will normally be called by that * object's cleanup routine. IT CANNOT BE CALLED WHILE THE REQUESTER * IS ACTIVE (ON SCREEN). * * The Following IGRemove functions perform similar functions, just * on a different structure category. */ void IGRemoveGadget (struct IGRequest *req,struct Gadget *rm); void IGRemoveImage (struct IGRequest *req,struct Image *rm); void IGRemoveBorder (struct IGRequest *req,struct Border *rm); void IGRemoveIText (struct IGRequest *req,struct IntuiText *rm); void IGRemoveSBox (struct IGRequest *req,struct SelectBox *rm); void IGRemoveIGObject (struct IGRequest *req,struct IGObject *rm); AllocCLBit Function /* Allocates CallLoop bit for IGRequest CallLoops */ BYTE AllocCLBit (struct IGRequest *req); FreeCLBit Function /* Frees CallLoop bit for IGRequest CallLoops */ void FreeCLBit (struct IGRequest *req,UBYTE bit); FindRexxGadget Function /* This routine finds a Gadget with a RexxName of name in a gadget list * pointed to by gadg. Used internally by IGRequest, but can also be used * by you. Returns null on failure. */ struct Gadget *FindRexxGadget (struct Gadget *gadg,UBYTE *name); IGInitRequester Function /* zeros values in Requester req, sets LeftEdge, TopEdge, Width, Height * values so that they are offsets from the edges of the window win */ void IGInitRequester (struct Window *win, /* Window values relative to */ struct Requester *req, /* Intuition Requester */ SHORT rl, SHORT rr, /* Left, right offsets from * Window edge */ SHORT rt,SHORT rb); /* Top, Bottom offsets from * Window edge */ /* NOTE: This routine calls Intuition's InitRequest, clearing any * data values previously in requester */ FindRexxMenu Function /* This routine finds a menu or submenu item with the RexxName of name in the requester described by the req IGRequest structure. It then returns a pointer to the IGMenu structure concerning it. This is used by the ARexx processing routines. */ struct IGMenu *FindRexxMenu (struct IGRequest *req,UBYTE *name); IGProcessRexxMsg Function /* Processes a RexxMsg for IGRequest req. Called internally by IGRequest * to implement the following Rexx commands: * * GadgetClick <RexxGadgetName> * SetStringGad <RexxGadgetName> <String> * KeyClick <qualifiers> <key> * MenuPick <RexxMenuName> * * Qualifers for KeyClick is a string like that sent to KeyClick above and * key should be the unqualified (non-shifted,controled,etc.) letter that * appears when the desired key is typed. * * If IGProcessRexxMsg doesn't understand the command, or can't find * the specified Gadget in this IGRequest, it returns 1. Otherwise it * returns 0. * * If this routine returns 1 when called from IGRequest, IGRequest will call * your ArexxFunction. If you don't have an ArexxFunction, it will set * the Result1 field to 10 before replying to the message. */ BOOL IGProcessRexxMsg (struct IGRequest *req,struct RexxMsg *rm); UpDateSBox Function /* Scroll Function in SBox's Prop's IGInfo should point to here */ /* The user doesn't have to worry about this, IGRequest takes care of it */ void UpdateSBox (struct IGRequest *req, struct Gadget *gadg, LONG x,LONG y); RefreshSBox Function /* Call this after you have added entries */ /* It redraws the SelectBox */ void RefreshSBox (struct IGRequest *req,struct SelectBox *sb); FixIDs Function /* Renumbers ID's in entries so that they are correct NOTE: A SELECT BOX WILL NOT WORK IF ITS IDS ARE NOT CONSECUTIVE STARTING AT 0 */ void FixIDs (struct SelectBoxEntry *first); MakeBox Function /* Allocates two border structures and SHORT values on the key, and creates Box, returns pointer to first Border structure */ struct Border *MakeBox (USHORT w, USHORT h, UBYTE c1, UBYTE c2, struct Remember **key); MakeSBEntryList Function /* using array of strings items, with num strings, it allocates SelectBoxEntry structures for each item and creates a entries list that can be used with a selectbox. Just set the SBox's Entries field to this functions return value. All allocations are make on the key */ struct SelectBoxEntry *MakeSBEntryList (struct Remember **key, char *items[],int num, void (*func) ()); FixLinks Function /* Goes through a list of SelectBoxEntries linked only by the Next field, and make the list doubly linked (both Next and Prev fields valid */ void FixLinks (struct SelectBoxEntry *first); AddSBEntry Function /* Adds a SelectBoxEntry toadd to the list currently being used by SelectBox sb. toadd is added at position pos, if pos==-1, it is added at the end */ void AddSBEntry (struct SelectBox *sb,struct SelectBoxEntry *toadd,int pos); AddEntry Function /* allocates a SelectBoxEntry on key, and sets its Text field to point to string entry, and its ItemSelected field to point to func, then adds the new entry to SelectBox sb at position pos */ BOOL AddEntry (struct SelectBox *sb, char *entry, void (*func) (), int pos); AddEntryAlpha Function /* Same as above, but inserts the entry into entry list in alphabetical order */ BOOL AddEntryAlpha (struct SelectBox *sb, char *entry, void (*func) () ); RemoveSBEntry Function /* Removes entry from SelectBoxes SelectBoxEntry List. Does not * free entry (which is necessary with entries added via AddEntry * and AddEntryAlpha). */ void RemoveSBEntry (struct SelectBox *sb,struct SelectBoxEntry *e); FreeSBEntry Function /* Frees SelectBoxEntry allocated with AllocMem, AddEntry, or * AddEntryAlpha */ void FreeSBEntry (struct SelectBoxEntry *e); ClearSBox Function This Function removes all a selectBox's entries void ClearSBox (struct SelectBox *sb,BOOL freeEntries); SBoxSelect/DSelectAll Function These functions select and deselect all of a SBox's entries respectively: void SBoxSelectAll (struct SelectBox *sb); void SBoxDSelectAll (struct SelectBox *sb); MakeIGFileRequest Function /* Set the InitFunction field of the IGObject structure to point to this function. The Address field must contain a pointer to an initialized IGFileRequest structure */ MakeIGFileRequest (struct IGRequest *req,struct IGObject *obj); ShowDir Function /* If you change the name in FileName, call this routine to show the directory */ void ShowDir (struct IGRequest *,struct IGFileRequest *); FixFile Function /* This routine updates the FileName Gadget */ void FixFile (struct IGRequest *req,struct IGFileRequest *fr); ChopLevel Function /* This routine will change the string FileName so that it contains one less directory level, or contains the directory short the filename*/ void ChopLevel (UBYTE *FileName); FixDirNameEnding Function /* This routine insures that a directory name ends either with ':' or '/', and if necessary appends a '/' so that you can strcat filenames onto a directory name easily */ void FixDirNameEnding (UBYTE *dirname); GetFileName Function /* This routine will copy the last part (after the last '/' or ':') of pathfile to file */ void GetFileName (UBYTE *pathfile,UBYTE *file); GetFRDirName Function /* This routine will take a path and file name, and copy it file minus a filename if one is present. Pathfile is assumed to have just come from fr (which has a flag bit set if a filename was present */ void GetFRDirName (UBYTE *pathfile,UBYTE *file, struct IGFileRequest *fr); UpDirectory Function /* This routine erases the last level from a file requester's filename and then calls FixFile */ void UpDirectory (struct IGRequest *req,struct IGFileRequest *fr); SetDirectory Function /* Sets given file requester to given directory */ void SetDirectory (struct IGRequest *,struct IGFileRequest *,UBYTE *dir); SelectFile Function /* Selects file in file requester, taking into account single select or multiselect modes. If necessary, waits until directory has been read. */ BOOL SelectFile (struct IGRequest *,struct IGFileRequest *,UBYTE *file); SetPathFile Function /* Selectively calls one or both of SetDirectory and SelectFile, depending on whether path is directory name of directory and file name or just file name. */ BOOL SetPathFile (struct IGRequest *,struct IGFileRequest *,UBYTE *path); DupDirList Function /* This function will duplicate a Directory Entry list, matching the criteria given in flags. If there is any chance of an IGFR routine running while you are looking through the DirEntry list (like IGFR freeing the list), duplicate it first to avoid problems. The following are flags you can use, in any combinations. IGDE_DISPLAYED Entries must match current file matching specs to be copied IGDE_SELECTED Entries must be selected (in MULTISELECT FileRequester's only IGDE_FILESONLY Entries must be files IGDE_DIRSONLY Entries must be directories IGDE_NOTDISPLAYED Entries must not match current file matching specs IGDE_NOTSELECTED Entries must not be selected (in MULTISELECT FileRequester's only IGDE_ALL Both files and directories will be copied Note: Do not write to the FileName field of duplicated IGDirEntry structures, or add entries to the linked list that were not created by the DupDirList function, as they will not be properly freed (read "The Computer will Guru") */ struct IGDirEntry *DupDirList(struct IGFileRequest *fr,ULONG flags); FreeDirList Function /* Use this function to free a linked list created by DupDirList */ void FreeDirList(struct IGDirEntry *de); IGFRSelectAll Function /* Selects all files in multiselect file requester */ void IGFRSelectAll (struct IGRequest *req, struct IGFileRequest *fr); IGFRDeSelectAll Function /* Deselects all files in multiselect file requester, Deselects selected file, if any, in single select file requester */ void IGFRDeSelectAll (struct IGRequest *req, struct IGFileRequest *fr);